Gold Medal Software 3

home *** CD-ROM | disk | FTP | other *** search

/ Gold Medal Software 3 / Gold Medal Software - Volume 3 (Gold Medal) (1994).iso / accounts / vndnfo10.arj / VENDPRCS.DOC < prev next >

Wrap

Text File | 1994-01-05 | 152KB | 4,072 lines

+----------------------------------------+ | | | | | User's Guide | | | | VendPrcs(TM) Processor | | for accessing VENDINFO(TM) records | | Version 1.00 | | | | | | Last updated: December 1993 | | | | | | Copyright 1993 Rams' Island Software | | All rights reserved | | | +----------------------------------------+ Rams' Island Software 7644 E. Lakecliff Way _______ Parker, CO 80134-5904 (USA) ____|__ | (R) --| | |------------------- Voice: (303) 841-2848 | ____|__ | Association of BBS: (303) 841-6269 | | |_| Shareware CompuServe: 76244,324 |__| o | Professionals -----| | |--------------------- FidoNet: 1:104/333 |___|___| MEMBER RIME: RAMSISLE Internet: 76244.324@CompuServe.Com VendPrcs User's Guide VendPrcs +-----------------+ | Acknowledgments | +-----------------+ Many people have helped to mold the VENDINFO vision, and to provide support and encouragement throughout its development process. Thanks are given to all those who have reviewed the Concept Paper or the VENDINFO standard, or who have otherwise made suggestions regarding the project. The author is especially grateful to Fred Hill and Richard Holler, for long-term support and help with VENDINFO. While many have reviewed parts of the VENDINFO documentation, special thanks go to Jim Green, for helping us avoid a wrong direction; to Bob Ostrander for a simple but particularly powerful idea; and to Daan van Rooijen, for really studying the standard and providing many, many useful suggestions. Many people have also helped in beta testing the VENDINFO tools, and we're grateful to them all. Special thanks are given to Steve Estvanik and Jerry Stern, for really giving things a workout, and tirelessly reporting the results. The VENDINFO team is grateful to the following shareware trade associa- tions for their endorsements of VENDINFO: Association of Shareware Professionals (ASP) Association of Shareware Authors and Distributors (ASAD) Shareware Trade Association and Resources (STAR) Educational Software CoOperative (ESC) Finally, we particularly appreciate the 30-or-so software development teams (mostly BBS-related) whose early commitment to support the VEN- DINFO standard in their software products has helped provide momentum and visibility to this effort. VENDINFO, VendEdit, VendPrcs, VendView, and VendLib are trademarks of Rams' Island Software. VendPrcs Processor v1.00 -ii- Dec 1993 VendPrcs User's Guide Table of Contents +-------------------+ | Table of Contents | +-------------------+ The VENDINFO System ................................................ 1 Components of the System ........................................ 1 Structure of a VENDINFO File .................................... 2 A Little Background ............................................. 3 Industry Support and Endorsements ............................... 4 Other VENDINFO Documents and Packages ........................... 5 Introduction to VendPrcs ........................................... 6 Installation ....................................................... 7 Quick Start ..................................................... 7 Detailed Contents of the VendPrcs Package ....................... 8 Warranty and License ............................................ 9 Technical Support for VendPrcs .................................. 9 Extracting Fields from a VENDINFO File (-x) ........................ 11 Simple Extraction of a Field Value (-x) ......................... 11 Multi-Line Field Values (-zr, -zc) .............................. 11 Indenting the Output (-zi) ...................................... 12 Inserting in Other Text (-y, -zi) ............................... 12 Special Format-Control Strings (-zd) ............................ 13 Alternative TRUE/FALSE Strings (-zt, -zf) ....................... 14 Multiple Extractions on One Line (-zn) .......................... 14 Truncating and Padding to Exact Width (-zw, -zl) ................ 15 Special Output Conventions (-zv) ................................ 15 Value Returned if Field is Empty ................................ 16 Special Extraction Formats (-s) ................................. 16 Improving Performance During Multiple Extractions (-zk) ......... 16 Errorlevels Returned by Extraction Operations ................... 17 Extraction Examples ............................................. 18 Testing for Field Values (-e) ...................................... 19 Errorlevels Returned by Field Tests ............................. 19 Testing Fields That Can Be Missing .............................. 19 Testing Boolean Fields .......................................... 20 Testing Other Always-Present Fields ............................. 21 Testing for Distribution Permission (-d) ........................... 22 Philosophy Regarding Distribution Restrictions .................. 23 Algorithm Used for Distribution Permission Tests ................ 24 Proposed Distribution Channel (-d) .............................. 25 Charges Made for Distribution Services (-c) ..................... 27 Distributor "Type" (-t) ......................................... 29 Indicating Details of the Distribution Medium (-m) .............. 29 VendPrcs Processor v1.00 -iii- Dec 1993 VendPrcs User's Guide Table of Contents Informing the Customer (-oi) .................................... 30 Modifying or Bundling Packages (-om) ............................ 30 Other Distribution Specifications (-o) .......................... 31 Errorlevels Returned by Distribution Permission Tests ........... 31 Testing for VENDINFO-Branded Executables ........................ 33 Testing for Altered Package Contents ............................ 33 Suppressing Unwanted Testing (-n) ............................... 33 Package Routing and Disposition (-r) ............................... 35 Routing Directory Conventions ................................... 35 Package Filename (-p) ........................................... 36 Rename Package to Author-Indicated Name (-rn) ................... 37 Move Package Based on Test Outcome (-rm) ........................ 38 Move Package Based on Product Category (-rc) .................... 38 Logs and Generated Lists (-rl -rs -rd -ro) ...................... 41 Maintain VENDINFO File Library (-rv) ............................ 42 Security ........................................................... 43 Putting It All Together (Examples) ................................. 45 Force Package to Author-Preferred Name .......................... 45 A Low-Maintenance Games-Only BBS ................................ 46 BBS-Ready CD-ROM Production ..................................... 47 Build FILES.BBS ................................................. 49 Automatic Permission Request .................................... 50 Appendix A -- VendPrcs Command-Line Arguments ...................... 51 Appendix B -- Field Code Reference ................................. 54 Author/Publisher Information .................................... 54 Channel-Specific Distribution Information ....................... 54 Human-Readable Front Text Sections .............................. 56 Channel-Independent ("General") Distribution .................... 56 VENDINFO Header Information ..................................... 57 Price and Benefits Information .................................. 57 Ordering Information ............................................ 58 Product Information ............................................. 59 Information about Distributors of Registered Version ............ 62 Technical Support Information ................................... 63 Special Information Not From Inside VENDINFO Record ............. 64 Appendix C -- VendPrcs Errorlevels ................................. 65 VendPrcs Processor v1.00 -iv- Dec 1993 VendPrcs User's Guide Introduction to VENDINFO +---------------------+ | The VENDINFO System | +---------------------+ VENDINFO is a system for conveying software product information and distribution permissions from the author to distributors. A standard (public) file format allows a VENDINFO.DIZ file to carry extensive information in a compressed, efficient form. The associated toolset aids the author in constructing the record, and allows the dis- tributor to extract portions of the record, or to make distribution decisions based on its content, in a highly automated way. VENDINFO provides unprecedented capabilities for o Communication of product information and distribution policies from author to distributor. o Automation of many aspects of package handling by shareware distributors of all types. Components of the System ------------------------ The VENDINFO "record" is the key. This is an efficiently compressed file (VENDINFO.DIZ) containing a great deal of information about the product, the author, and the product's distribution policies. The VendEdit editor allows the author to construct a complete VENDINFO record in just a few minutes, assuming that the necessary descriptive texts have already been prepared. The VendPrcs (pronounced "vend process") processor is a batch program allowing automated decisions based on VENDINFO content, and automated extraction of VENDINFO information. VendView is a simple viewer allowing the end-user to see relevant portions of the VENDINFO data. This program should be available by February 1994. Even without VendView, an ordinary text viewer will display a good deal of useful information. The Product Registry is a collection of VENDINFO records available for searches and queries by subscription, BBS login, or mail-order query. This service will begin in January 1994. The VendLib Library allows software developers to build VENDINFO access directly into such products as BBS programs and upload proces- VendPrcs Processor v1.00 -1- Dec 1993 VendPrcs User's Guide Introduction to VENDINFO sors. This library is already in the hands of some 30 vendors of BBSes, BBS utility software, and other relevant software. The file-format standard describing the VENDINFO file is public, and draft versions have been published since July 1993. The final version 1.00 has been released, and is the basis for the current toolset. VendPrcs Plus, a non-shareware version of VendPrcs, is planned for release by Spring 1994. It will have a full-screen interface, using scripts for easier, more efficient information extraction, and templates for easier description of decision situations. It will also allow management of a library of VENDINFO files, and will provide automated access to the Product Registry BBS. Additional services for authors, users, and distributors are under consideration. Structure of a VENDINFO File ---------------------------- The VENDINFO.DIZ file contains two sections. A human-readable front section contains information about how to use the VENDINFO file, and presents most of the basic information about the product in readable form. The second section is a binary data record, compressed with a PKZIP 1.10 algorithm, and appended to the file after the first section. This record has some 750 fields of information about such things as o Product name, date, and version o Preferred package filename, other parts of product, replaced versions o Product descriptions of varying length, categories, keywords o Required platform (CPU, operating system, memory, disk, features) o Contact information for author, for registering, for tech support o Registration prices and benefits, acceptable forms of payment o Warranty and trial-use license o Detailed distribution policy, in general and by distribution channel VendPrcs Processor v1.00 -2- Dec 1993 VendPrcs User's Guide Introduction to VENDINFO o Information about regional distributors and registration services. A Little Background ------------------- The author of the VENDINFO standard and tools, Rudy Ramsey, has been agitating since early 1992 for the development of an improved mechanism for conveying product information and permissions from authors to distributors. Initially, the intent was to make this a purely volunteer-based effort, probably conducted within the auspices of the Association of Shareware Professionals. However, others were slow to respond to the idea (with the exception of Richard Holler and Fred Hill), and it gradually became clear that it would have to be done as an "extracurricular" effort, if at all. In the Spring of 1993, Rudy began the VENDINFO effort in earnest, by preparing the CONCEPT.DOC concept paper and distributing it to a few key shareware industry figures for comment. (At this time, he still imagined VENDINFO as an all-volunteer effort.) The reviewers were uniformly excited about the idea, and greatly encouraging. Most felt that it was an idea whose time had come, and that the technical approach described in the concept paper was very appropriate. Their second response, however, was that the effort contained the seeds of its own failure. It might provide all the necessary incen- tives for participation by authors, distributors, and users. But if it didn't also provide an incentive for continued development and support by its own development team, it would fail. It was simply too big an activity for successful execution by volunteers. As a result of that input, a decision was made to regard VENDINFO as partly a business opportunity. Although this makes a few people suspicious, most agree it's in the best interest of the VENDINFO effort itself, and of the industry. In fact, VENDINFO has developed rapidly, partly because it has been a full-time focus of its author for many months. That wouldn't have been possible in an all-volunteer effort. The VENDINFO file-format standard is public. A substantial period was provided for public comment on the concept paper, and then on the standard, and public input is always welcome. Some of the tools that make use of the standard are free (a viewer for end users, and the processor when used by single-line, noncommercial BBSes). Most are low-cost shareware. There will also be much-enhanced, non-shareware programs later, for special purposes, but none of them are necessary to achieve the benefits of the VENDINFO system. VendPrcs Processor v1.00 -3- Dec 1993 VendPrcs User's Guide Introduction to VENDINFO Industry Support and Endorsements --------------------------------- Support for the VENDINFO concept has been extraordinarily high throughout the industry. Authors, disk vendors, CD-ROM publishers, Sysops, and BBS software manufacturers have all expressed their support, and many have pledged to build VENDINFO capability into their own software products. The following shareware trade groups have formally endorsed the VENDINFO file-format standard as a means of conveying product and product-distribution information from authors to users and dis- tributors. Association of Shareware Professionals (ASP) Shareware Trade Association and Resources (STAR) Association of Shareware Authors and Developers (ASAD) Educational Software CoOperative (ESC) The ASP has licensed the VENDINFO toolset for use by all 1700 of its members. This will greatly accelerate the use -- and the usefulness -- of VENDINFO. The following software manufacturers have "committed in principle" to support VENDINFO in their own software offerrings by mid-1994. In the context of these products, "support" for VENDINFO means extracting relevant descriptive information automatically from VENDINFO files. It does not necessarily mean making decisions based on the product's distribution policy. VendPrcs will provide that capability. BBSes PCBoard, Clark Development Co. Wildcat!, Mustang Software, Inc. Major BBS, Galacticomm RBBS, RBBS Development Team Searchlight BBS, Searchlight Software TBBS, eSoft Auntie BBS, Wes Meier Executive Host BBS, Steve Wood MainLine BBS, Scott Green, City Limits Software OmegaComm BBS, Larry Loiselle PowerBBS for Windows, Russell Frey ProBoard BBS, Philippe Leybaert Sapphire BBS, Pinnacle Software Tinyhost, Bruce Krobusek UltraBBS, UltraBBS Software Windowed Modem Environment, Jason Fesler VendPrcs Processor v1.00 -4- Dec 1993 VendPrcs User's Guide Introduction to VENDINFO File Upload Processors CatScan, Mike Ortiz CheckZip, Bill Hull DIZIT, Robert Neal/CorpSoft HoboScan, Floyd Hobson TransScan, Craig Dunstan File Distribution Processors WCFF, Online Computer Resources Other Products *BBSee Disk Cataloger, Martin Vallevand *Catalog-on-a-Disk, EmmaSoft Software Company, Inc. Colorado Utilities Disk Manager, Micro Systems Solutions SmartCat Disk Cataloger, Oakley Data Services * Test versions are known to exist which support VENDINFO Other VENDINFO Documents and Packages ------------------------------------- The VENDINFO idea is documented in a concept paper and in the VEN- DINFO file-format standard. These two documents are available in the VENDINFO package, usually named VNDINFxx.ZIP. It can be obtained from the Rams' Island BBS on first login or by FidoNet or RIME file re- quest (magic name VENDINFO). It is also available in the CompuServe SHAREWARE and UKSHARE forums; the ASP Hub Network BBSes, many local BBSes, from some disk vendors, and on the ASP CD-ROM. If necessary, the concept paper and evaluation versions of the basic toolset can be obtained on diskette from Rams' Island Software for US$ 8.00 plus $2.00 shipping and handling in North America, $4.00 elsewhere (starting January 1994). Payment is accepted by Visa/MasterCard, check in U.S. dollars drawn on a U.S. bank, cash in any hard currency (registered mail suggested), and various other forms. An article about the VENDINFO system will appear in the November/December 1993 issue of Shareware Magazine. VendPrcs Processor v1.00 -5- Dec 1993 VendPrcs User's Guide Introduction to VendPrcs +--------------------------+ | Introduction to VendPrcs | +--------------------------+ VendPrcs is a powerful, batch-oriented tool for extracting and using information from VENDINFO records. VendPrcs provides many more capabilities than will be needed by any single user, because: o It is used in different ways by different user types (sysops, disk vendors, CD-ROM publishers, authors, etc.), and o The VENDINFO file contains a great deal of information (roughly 750 fields). To avoid overloading the reader with a large number of command-line options, we've broken the discussion down into several chapters, each describing one way of using VendPrcs. Appendix A summarizes all the command-line options, in case you need it for reference. There are four basic ways of using VendPrcs, and they are discussed separately in the four chapters following "Installation". o Extracting individual fields from the VENDINFO record, in order to print them, enter them into a database, etc. o Testing for the presence of specific (non-empty) fields in the record. o Testing for distribution permissions conveyed by the record. o Using VendPrcs to assist in the disposition of packages, such as routing them to different file areas on a BBS. VendPrcs Processor v1.00 -6- Dec 1993 VendPrcs User's Guide Installation +--------------+ | Installation | +--------------+ To install VendPrcs, simply copy VENDPRCS.EXE to a directory on your path. If you will be extracting product category information from VENDINFO records, you have the option of extracting either category code numbers, such as 14010200 or the corresponding category text descriptions, such as Point-of-sale systems If you want the latter, you must also copy CATEGORY.INF to the same directory to which you copied VENDPRCS.EXE. If you will be testing for distribution permissions, you may also wish to copy the file VPRESULT.CFG into that same directory. You will have to modify this file with a text editor. You may also want to make a copy of CATEGORY.INF in that directory with the name VPCATGRY.CFG, and modify it to the required form. See the chapter "Package Routing and Disposition" for more information. You should also take a look at EXAMPLES.ZIP, an included ZIP file containing examples of two kinds: o Example VENDINFO files (*.DIZ), and the corresponding content printouts (*.PRN). o Example batch files (*.BAT) showing various ways of using VendPrcs. These are also discussed in the chapter, "Putting It All Together (Examples)". Quick Start ----------- There really isn't a very "quick" starting technique for VendPrcs. Since it's a command-line oriented batch program, it has no on-line help, and you'll have to become familiar with the command flags necessary for your particular use of the program. Still, it will be quickest for you if you read the following chapters VendPrcs Processor v1.00 -7- Dec 1993 VendPrcs User's Guide Installation of this User Guide Introduction to VENDINFO (earlier in this user guide) Introduction to VendPrcs (earlier in this user guide) and then read the chapter(s) devoted to the particular purposess for which you will be using VendPrcs. Finally, read the "Putting It All Together" chapter. Detailed Contents of the VendPrcs Package ----------------------------------------- The VENDINFO toolset package contains all files required to use either the VendEdit editor or the VendPrcs processor. This allows either to be used to verify the functioning of the other. For a complete list of files in the package, see VENDEDIT.DOC. The VENDINFO toolset package includes the following files that are specifically relevant to the VendPrcs processor: VENDPRCS.DOC This document. VENDPRCS.EXE The VendPrcs executable program. REGISTER.FRM Registration form for VendPrcs, and several other products and services associated with the VENDINFO system. CATEGORY.INF Product category information file, which defines the category code structure and maps the codes to readable text. VPRESULT.CFG Sample VendPrcs configuration file defining direc- tories used by VendPrcs to move packages according to test results. EXTRACT.BAT A batch file used for extracting all fields from a VENDINFO.DIZ record. EXTRDIST.BAT A batch file used for extracting distribution policy information for a single channel from a VENDINFO.DIZ file. This batch file is called from EXTRACT.BAT. EXTRREGL.BAT A batch file used for extracting information about distributors of your registered version. This batch file is called from EXTRACT.BAT. VendPrcs Processor v1.00 -8- Dec 1993 VendPrcs User's Guide Installation TESTDIST.BAT A batch file used to perform a variety of distribu- tion policy tests on a VENDINFO.DIZ file. EXAMPLES.ZIP PKZIP-compressed file containing VendPrcs example files (*.DIZ), corresponding printout of their content (*.PRN), and a few additional batch files illustrating uses of VendPrcs (*.BAT). VENDINFO.DIZ The VENDINFO.DIZ file that describes this whole VENDINFO toolset package. As a further introduc- tion, it's worth viewing with a text viewer. It also contains the IMPORTANT warranty and license agreements applicable to use of VendPrcs. Warranty and License -------------------- VendEdit and VendPrcs are shareware products, which you may fully evaluate before deciding whether or not you wish to purchase them. The Warranty and License governing your use of these products will be found in the VENDINFO.DIZ file (read it or print it with the tools you use for ordinary text files). The License Agreement for the VENDINFO toolset is a little more complicated than most, and it is important that you familiarize yourself with it. You'll find it in the VENDINFO.DIZ file that came with the toolset, as well as in the VendEdit help system. In addition to the normal functions of a license agreement, this one serves an important role in the VENDINFO system. By requiring authors to agree to a few simple conditions, it helps protect the rights of distributors and the confidence with which distributors can use the VENDINFO system in a fully automated way. Similarly, distributors must agree to a few conditions that help protect the author. Details are explained in the license itself. Technical Support for VendPrcs ------------------------------ If you have a problem with installation or use of this product, and the documentation doesn't provide the help you need, you are welcome to contact us. You can do this in any of several ways. RAMS' ISLAND BBS The Rams' Island BBS is a bulletin board system, accessible to you if if you have a modem and communication software. On our BBS, you will VendPrcs Processor v1.00 -9- Dec 1993 VendPrcs User's Guide Installation always find the latest version of the program, and you will be able to ask technical questions of us and of our other users. We also offer additional utilities, class definitions, application notes, and other assistance to registered users via the BBS. The BBS phone number is 303-841-6269. COMPUSERVE INFORMATION SYSTEM We also support this product on the CompuServe information system. The latest version of the program is always available there in the SHAREWARE and UKSHARE forums, and technical questions and support requests may be sent to us via electronic mail there or on the CompuServe SHAREWARE and UKSHARE forums. Our CompuServe user ID is 76244,324. BBS NETWORK FORUMS We have established VENDINFO support forums on both the FidoNet and RIME networks. We are investigating a VENDINFO forum on GlobalNet. OTHER ELECTRONIC ADDRESSES You can reach us through three other computer networks (you can usually find a local BBS that's also on these networks). Our FidoNet address is 1:104/333. Our RIME address is 1235 or RAMSISLE. Our Internet address is 76244.324@compuserve.com. VOICE TELEPHONE You may reach us by voice telephone at 303-841-2848. MAIL You may contact us by mail at Rams' Island Software 7644 E. Lakecliff Way Parker, Colorado 80134-5904 USA VendPrcs Processor v1.00 -10- Dec 1993 VendPrcs User's Guide Extracting Fields +---------------------------------------------+ | Extracting Fields from a VENDINFO File (-x) | +---------------------------------------------+ With very few exceptions, every field in a VENDINFO record has a unique code by which it can be referenced. For example, the code for a product name is "pp" (Appendix B contains a complete list of field codes). The -x ("eXtract") command-line option causes field values to be extracted. The -y and -z options specify further details of the extraction operation. Simple Extraction of a Field Value (-x) --------------------------------------- Given the field code for a desired field, extraction of the value of the field can be done with the -x ("eXtract") option. To obtain the product name, for example, the command is vendprcs vendinfo.diz -xpp This command, expressed in plain English, would be, "Run VendPrcs on the file VENDINFO.DIZ, extracting the value of the field 'pp'." Execution of this command would cause the product name field to be written to stdout (i.e., to the video screen unless standard output has been redirected). Multi-Line Field Values (-zr, -zc) ---------------------------------- Some fields, such as product descriptions, are inherently more than one line long. In other cases (a keyword list, perhaps), you may choose to extract a field in multiple lines, in order to limit the width of the result. The -zc ("Columns") and -zr ("Rows") options allow you to limit the width and height, respectively, of a multi- line output. Here's a simple example: vendprcs vendinfo.diz -xpd -zc45 -zr10 > FILE_ID.DIZ This command causes VendPrcs to extract the largest product descrip- tion ("pd") that will fit in 10 rows by 45 columns, and redirects the result to FILE_ID.DIZ. This is a simple way to create a FILE_ID.DIZ file from a VENDINFO.DIZ file, if needed. (Note that "pd" is a spe- VendPrcs Processor v1.00 -11- Dec 1993 VendPrcs User's Guide Extracting Fields cial field code meaning the largest description that will fit in the defined space.) VendPrcs uses word-wrapping whenever a column limit is specified. If the space allowed is less than the amount of information in the field, VendPrcs will fill the space using word-wrap, and ignore any remaining text. A typical example might be: vendprcs vendinfo.diz -xpk -zc40 -zr2 which will produce a list of product keywords no more than 2 x 40 characters in size. The -zc option can be used by itself, without a row limitation, in which case additional rows of the specified width will be produced until the entire field has been extracted. Indenting the Output (-zi) -------------------------- Extracted output can be indented by any desired number of columns through use of the -zi ("Indent") option. For example, to produce a long product description with 5-character margins on an 80-column screen, this command would be used: vendprcs vendinfo.diz -xpd6 -zi5 -zc70 This specifies a 5-column indentation on the left, and up to 70 columns of actual text. Inserting in Other Text (-y, -zi) --------------------------------- In many cases, you may wish to surround an extracted value with other text. For example, you might want to precede the value with a label. Here's an example: vendprcs vendinfo.zip -xpp -y "Product Name: @" >> temp This command extracts the product name and places it in the "label string". If the label string contains a single "@" character, the extracted string will be substituted for it. Thus, the output of this command might be: Product Name: InContext VendPrcs Processor v1.00 -12- Dec 1993 VendPrcs User's Guide Extracting Fields If the character "@" is needed in the output, use a pair of "@" symbols. Thus, vendprcs vendinfo.diz -xpp -y "@@Product = @" might produce part of a Ventura Publisher text file containing a style tag ("@PRODUCT = "); The -y option can be used alone to simply echo text without reading a VENDINFO file or extracting any field values. vendprcs -y "Product Information" > TEMP The -y and -zi options can be used together, to control a multi-line extraction. For example, the command: vendprcs vendinfo.diz -xpd -zc45 -zr3 -zi13 -y "Description: " produces a description like: Description: Exemplar Sample Program V1.00. Does just about everything, including bread baking and lawn mowing. Shareware. Notice that the label string (-y) applies only to the first line of output. Notice also that, in the presence of the -y option, the indentation (-zi) applies only to subsequent lines of the same field. Special Format-Control Strings (-zd) ------------------------------------ A few fields (dates and prices) can be produced under partial control of a user-specified format. Such formats are specified with the command-line option -zd ("Date", "Decimal"). For example, vendprcs vendinfo.diz -xpt -zd "mm/dd/yy" extracts the product's release date in the form usually encountered in the United States (e.g., 10/4/93). This is also the default format for dates, if no format-control string is given. A typical United Kingdom format is "dd-mm-yy". Any desired separator can be used, including blanks. The following symbols are used to indicate where the various components of the date are placed: d == day (1 to 31) m == month (1 to 12) M == month (Jan to Dec) VendPrcs Processor v1.00 -13- Dec 1993 VendPrcs User's Guide Extracting Fields y == year (2 digits if before 2080, else 4) Y == year (4 digits, as "1993") Repetition of the field characters is optional. Thus, "mm/dd/YYYY" is equivalent to "m/d/Y". Similarly, price information can be output using different characters for the decimal point. The default is ".". To use, say, a comma as the decimal-point symbol, you would use a command like: vendprcs vendinfo.diz -zi1p -zd "," Alternative TRUE/FALSE Strings (-zt, -zf) ----------------------------------------- All extracted fields are returned as strings. This includes boolean (yes/no) fields, whose values are returned as either "TRUE" or "FALSE". You can cause VendPrcs to return other values for boolean variables, by specifying the strings on the command line, using the -zt ("True") and -zf ("False") options. Thus, vendprcs vendinfo.diz -xama -y "ASP member? @" -zt "Yes" -zf "No" might produce something like ASP member? Yes If you specify only a string for TRUE, output will be suppressed if the field value is FALSE (and vice versa). Thus vendprcs vendinfo.diz -xama -zt "(ASP)" might be used to add "(ASP)" to the end of a description. Multiple Extractions on One Line (-zn) -------------------------------------- By default, each VendPrcs extraction produces a separate line of text. In some cases, though, you may wish to extract several field values within a single line of output. For this purpose, the -zn (suppress Newline) option is used. For example: vendprcs vendinfo.diz -xpp -zn -y "Product: @ " > TEMP vendprcs vendinfo.diz -xpe -zn >> TEMP vendprcs vendinfo.diz -xpv -zn -y " v@" >> TEMP vendprcs vendinfo.diz -xpt -y " (@)" >> TEMP VendPrcs Processor v1.00 -14- Dec 1993 VendPrcs User's Guide Extracting Fields produces an output like this: InContext Work Environment Manager v1.10 (2/19/93) The -zn feature can be used along with -zt to produce a list on one line. For example, vendprcs vendinfo.diz -y "Registration Benefits: " -zn vendprcs vendinfo.diz -xi1bad -zn -zt "A" vendprcs vendinfo.diz -xi1bbs -zn -zt "B" vendprcs vendinfo.diz -xi1bcu -zn -zt "C" ... can produce a list of single-character codes to indicate registration benefits in a catalog: Registration Benefits: ABFHPW Truncating and Padding to Exact Width (-zw, -zl) ------------------------------------------------ The -zw ("Width") option specifies exact output width, and the field value is truncated or blank-padded to the specified width. If the -zl ("Left pad") option is also specified, any necessary padding is added at the left of the output. For example, vendprcs vendinfo.diz -xpp -zw12 -zl -zn can be used repeatedly to produce the filename column in a multi- column file list. Special Output Conventions (-zv) -------------------------------- Ventura Publisher requires a special output convention in order to preserve the format of a multi-line field. The characters "<R>" indicate where a newline ("return") should be retained. The -zv ("Ventura") option causes multi-line fields to be output in this way. Thus, vendprcs vendinfo.diz -xaa -zv -y "@@ADDRESS = @" produces an output like VendPrcs Processor v1.00 -15- Dec 1993 VendPrcs User's Guide Extracting Fields @ADDRESS = Rams' Island Software<R> 7644 E. Lakecliff Way<R> Parker, CO 80134-5904 which will retain its 3-line shape when used as an input to Ventura. We will be happy to add additional codes for other ASCII-file-based word-processor or page-layout tools. Let us know what you need. Value Returned if Field is Empty -------------------------------- If an attempt is made to extract the value of a field that is empty, the value "(none)" is returned. Special Extraction Formats (-s) ------------------------------- VendPrcs is capable of producing fully formatted outputs for special purposes. At present, the only such output is a catalog entry for "Catalog-on-a-Disk", a shareware program from EmmaSoft Software Company, Inc. To produce such a catalog entry, use the command vendprcs <diz_file> -sc<control_string> -zr<rows> The optional control_string has the following form [c][#order_nbr][$price] where all components are optional. The "c" argument causes the com- pany name to be printed at the end of the description. If no order_nbr is given in the control string, and the diz_file is VENDINFO.DIZ, the resulting entry will contain no order number. Otherwise, the filename prefix will be used as the order number. The row specification (-zr) will control the total length of the catalog entry. Improving Performance During Multiple Extractions (-zk) ------------------------------------------------------- The default behavior of VendPrcs, when doing an extraction, is to do the following each time it is invoked: 1. Read the entire VENDINFO file. VendPrcs Processor v1.00 -16- Dec 1993 VendPrcs User's Guide Extracting Fields 2. Extract the compressed data record to a temporary file (VI_TEMP.ZIP). 3. Decompress ("unzip") the compressed data record, storing it as another temporary file (VENDDATA.). 4. Read the data record, now decompressed, into memory. 5. Perform the extraction indicated by the command-line argu- ments. 6. Delete the temporary files. If multiple extractions (or other operations) are being performed on the same VENDINFO file, it will be advantageous to perform opera- tions 1, 2, and 3, above, just once. That can be done using the -zk ("Keep") option. This option prevents the VENDDATA temporary file from being deleted, allowing it to be reused. Here's an example of the sequence: vendprcs vendinfo.diz -xpp -zk vendprcs venddata -xpe vendprcs venddata -xpv ... del venddata The -zk argument causes the uncompressed VENDDATA file to be retained. Because the subsequent VendPrcs invocations make use of the special filename "VENDDATA", they will make use of the already prepared VENDDATA file, and they will not delete that file. This can cut total execution time by more than 80%. Please note, however, that use of the VENDDATA filename automatically suppresses any tests that depend on the front text. Errorlevels Returned by Extraction Operations --------------------------------------------- The following errorlevels may be returned by VendPrcs as a result of extraction operations: Errorlevel Meaning 1 An error has occurred. This is probably an incorrect field code, but it might be due to other causes, in which case an error message should be written to stderr. 10 VENDINFO file has wrong size or CRC for VendPrcs Processor v1.00 -17- Dec 1993 VendPrcs User's Guide Extracting Fields either the text or data section, and may be a hacked or corrupted file. 11 VENDINFO file has missing or invalid author authentication codes, and may be a hacked or corrupted file. 52 Extraction of a field value has been requested, and performed successfully (return of "(none)" for a missing value is regarded as a success). It is a good idea to test for errorlevels 10 and 11 after the first VendPrcs command executed on a given VENDINFO file. Further tests for those particular errorlevels should be unnecessary. Extraction Examples ------------------- Several batch files are provided with this toolset, both to provide specific capabilities, and to serve as examples. EXTRACT.BAT Extracts all field values from a VENDINFO file, writing them with labels to the file TEMP. This batch file contains examples of many of the fea- tures discussed in this chapter. It also serves as an excellent verification tool for authors who have prepared a VENDINFO file. (Be warned! This procedure takes awhile to run!) CATENTRY.BAT Prepares a catalog-type product description in Ventura Publisher format, with style tags. MAKFILID.BAT Creates a FILE_ID.DIZ file, for use with BBS software that supports that convention and does not yet support VENDINFO.DIZ. VendPrcs Processor v1.00 -18- Dec 1993 VendPrcs User's Guide Testing Fields +-------------------------------+ | Testing for Field Values (-e) | +-------------------------------+ The -e ("Exists") option is used, together with the field code (see Appendix B) to test for the presence of useable information in a field. Errorlevels Returned by Field Tests ----------------------------------- When used in this way, VendPrcs returns one of the following error- levels, which can be tested in a batch file: Errorlevel Meaning 1 An error has occurred. This is probably an incorrect field code, but it might be due to other causes, in which case an error message is written to stderr. 10 VENDINFO file has wrong size or CRC for either the text or data section, and may be a hacked or corrupted file. 11 VENDINFO file has missing or invalid author authentication codes, and may be a hacked or corrupted file. 50 A test for existence of a field value has been requested, and the result is TRUE. 51 A test for existence of a field value has been requested, and the result is FALSE. It is a good idea to test for errorlevels 10 and 11 after the first VendPrcs command executed on a given VENDINFO file. Further tests for those particular errorlevels should be unnecessary. Testing Fields That Can Be Missing ---------------------------------- For the text fields in a VENDINFO record, and a few others, it is physically possible to have an "empty" field. For example, the VendPrcs Processor v1.00 -19- Dec 1993 VendPrcs User's Guide Testing Fields author's "Delphi user ID" field would be empty if the author had no Delphi user ID. No harm is necessarily done if you extract (-x) the value of an empty field; the value "(none)" is returned. However, if you wish to test a field for presence of a value, you need to use the -e option. Thus, the batch file segment vendprcs vendinfo.diz -eaed if errorlevel 51 goto nodelphi ... <executed if Delphi ID exists> :nodelphi illustrates a test for the presence of an author's Delphi electronic address. Testing Boolean Fields ---------------------- Many fields in a VENDINFO record are "boolean" fields. That is, they always have a value, and the value is either "TRUE" or "FALSE". Since these fields always have a value, a test for existence of the value would be irrelevant. Therefore, VendPrcs returns the value itself, when such a field is tested using the -e option. For example, vendprcs vendinfo.diz -eams if errorlevel 51 goto nostar ... <executed if STAR member> :nostar tests whether or not the author/publisher is a member of the STAR trade association. If it isn't clear to you whether or not a particular field is boolean, you can find out by looking at the descriptive text for the field in Appendix B. If it ends in a question mark, ams Shareware Trade Association and Resources (STAR)? the field is boolean. VendPrcs Processor v1.00 -20- Dec 1993 VendPrcs User's Guide Testing Fields Testing Other Always-Present Fields ----------------------------------- There are other types of fields that always have a value. A price, for example, can be meaningful even if its value is zero. Platform features always have a value, even if it's "Irrelevant" or "Unknown". For such fields, a -e existence test is meaningless, and always returns a TRUE value. VendPrcs Processor v1.00 -21- Dec 1993 VendPrcs User's Guide Distribution Testing +------------------------------------------+ | Testing for Distribution Permission (-d) | +------------------------------------------+ To test for distribution permission, you simply describe the proposed distribution using command-line flags. VendPrcs compares the proposed distribution with the product's distribution policy, and indicates the result by DOS errorlevel and via a readable log. The DOS error- level indicates whether or not the distribution is allowed, and whether or not any additional conditions must be satisfied. The readable log contains a fairly detailed record, allowing you to easily see the details of any unsatisfied condition. Here's a simple example: vendprcs vendinfo.diz -db -c0 In plain English, this says, "I propose to distribute this product to end users via a BBS; no charges are made to users for use of the BBS or for downloading the product; is this OK?" Here's a much more sophisticated example, just to help you see the scope of the automated distribution testing provided by VendPrcs. vendprcs vendinfo.diz -dd -ck500 -cp500 -cy0 -mh -oisdop -os -ta In plain but rather lengthy English, this says, "I propose to dis- tribute this product to end users as a mail-order disk vendor; I charge no more than US$ 5 per 360K diskette or equivalent, no more than US$ 5 per product, and no yearly (monthly, etc.) subscription or membership fee; the product will be distributed on a single-product, high-density diskette; the customer will be informed that the product is shareware, informed of the nature of shareware, informed that I claim no ownership of the product, and informed that separate payment to the author is required if the product is used outside the author's evaluation terms; I will provide the author with a sample of my catalog or of his catalog description; I am an ASP vendor member; is this OK?" VendPrcs is easy to use within a batch file. Once you have determined the command-line switches that describe how you distribute shareware products, and the errorlevels that may result, you should be able to develop a fully automated procedure that can handle all the straightforward cases automatically, and which can call your atten- tion to the others for manual handling. The latter cases will be much easier to handle than without VendPrcs, because all or most of the necessary information will be extracted from the author's distribu- tion policy and written to the log file. VendPrcs Processor v1.00 -22- Dec 1993 VendPrcs User's Guide Distribution Testing Philosophy Regarding Distribution Restrictions ---------------------------------------------- Both authors and distributors will make more effective use of the VENDINFO system if they understand the point of view from which the system was designed. That point of view is outlined below. Regarding distribution restrictions by author/publishers: o The author should be able to express any possible distribu- tion restrictions, regardless of whether or not such restric- tions are well-advised. o Common and/or reasonable restrictions should be encoded in the VENDINFO record in such a way that automated tools can deal with them. o Other distribution restrictions should be expressible in text form, even if their presence will force conscientious dis- tributors to handle the package manually. o None of this should be taken as an encouragement for authors to impose distribution restrictions. In many cases, the documentation and help text of the VendEdit editor explicitly discourage restrictions. As an example, the author is advised to consider carefully before imposing ANY restriction on BBS distribution. o Authors will especially be warned against unnecessary use of options that force manual handling by distributors. Regarding testing for distribution permission: o In general, a proposed distribution is assumed to be NOT allowed until the distributor clearly addresses each condi- tion required by a product's distribution policy. This isn't done to constrain distribution or to make life difficult for distributors. It is done to protect all parties from acci- dents, misunderstanding, and even legal liability. Thus, if a product can be distributed by a disk vendor only if the per- disk charge is less than $10, VendPrcs will not "OK" the distribution because the vendor fails to mention the amount charged. There are a LOT of command-line switches in VendPrcs, but most dis- tributors will find it quite simple to select the options applicable to their particular situations. The VendPrcs log will help here, by showing what conditions haven't been satisfied, along with the op- tions that would have satisfied them. This will help the distributor VendPrcs Processor v1.00 -23- Dec 1993 VendPrcs User's Guide Distribution Testing to fully describe the situation, gradually eliminating unnecessary manual handling. Algorithm Used for Distribution Permission Tests ------------------------------------------------ Based on the information you provide on the VendPrcs command line, and the distribution policy specified in the VENDINFO file, VendPrcs determines whether or not your proposed distribution satisfies the author's requirements. To do this, VendPrcs looks at the author's policy for the particular distribution channel you've indicated, as well as the channel-independent ("general") distribution restrictions in the VENDINFO file. The actual decision process works as follows. (The important thing to understand is the last step, but you may find it useful to understand the whole decision process.) o If distribution via the proposed channel is prohibited, then "reject". o See if distributor is "qualified". The author might indicate that all distributors are qualified. If not, you must meet at least one of the author's qualification criteria to be in this set. Example criteria are: ASP member, non-profit user group, agreeing to "fully inform" your customers. o If distributor is "qualified", see if any specific behavior removes this "qualified" status, such as charging customers more than allowed. o Distributor is now either "qualified" or "disqualified". The meaning of this distinction is specified by the author. There are three possibilities: 1. Qualified may distribute without written permission. Disqualified may distribute only with written permission. 2. Qualified may distribute without written permission. Disqualified may not distribute at all. (Obviously, with the author's written permission, you can do anything you want; what the author is really telling you is that written permission won't be given.) 3. Qualified must still have written permission. Others may not distribute at all. o Based on your qualified/disqualified status, VendPrcs deter- mines whether or not you need written permission, and whether VendPrcs Processor v1.00 -24- Dec 1993 VendPrcs User's Guide Distribution Testing or not your proposed distribution is prohibited. If written permission is required, VendPrcs determines whether or not you've obtained it; if not, this requirement is noted in the log and will affect the errorlevel returned by VendPrcs. o If the distribution is allowed, either with or without writ- ten permission, VendPrcs looks for any additional author- specified conditions you must satisfy, and determines from the command-line flags whether or not you've satisfied them. If any conditions remain unsatisfied (including conditions specified by the author in text form), they are noted in the log and will affect the errorlevel returned by VendPrcs. o Unless you've disabled VendPrcs testing of executables, all *.EXE, *.COM, *.DLL, *.LIB, etc. files in the package are scanned for VENDINFO records, and a similar decision process is applied to any that are found. This feature is used to detect registered-user versions and commercial and other software not intended for further distribution. (See the later section, "Testing for VENDINFO-Branded Executables". o VendPrcs now informs you by DOS errorlevel that: 1. Distribution is prohibited by the VENDINFO file. 2. Distribution is prohibited by some included executable. 3. Distribution is OK if you satisfy additional requirements. 4. Distribution is OK if you obtain written permission. 5. Distribution is OK if you obtain written permission AND satisfy additional requirements. 6. Distribution is approved as-is. Proposed Distribution Channel (-d) ---------------------------------- The most fundamental information you need to specify is the proposed distribution channel. The -d<channel> command-line option allows you to indicate this using a one-letter code, as follows: b = Bbs f = bbs File-distribution network (FDN) d = mail order Disk vendor c = Cd-rom o = One-site rack vendor r = multi-site Rack distributor k = booK enclosure disk s = Subscription service VendPrcs Processor v1.00 -25- Dec 1993 VendPrcs User's Guide Distribution Testing m = Magazine t = Television/cable/satellite and similar p = 1-900 Phone distribution or similar i = Installation by distributor on end-user's machine u = other method Undescribed by above Thus, a sysop would include -db on the command line, while a mail-order disk vendor would include -dd There are a few special definitions that allow similar or unusual distribution channels to be covered by the list above. BBS Distribution to End User by BBS. Distribution *to* BBSes is covered by separate channels, especially FDN. Note: if a sysop wishes to send products to users via means other than download (e.g., mailed on diskette), it is necessary to use the -md flag. FDN File Distribution Network Distribution *to* BBSes. Note: if an FDN uses non-electronic means, such as CD-ROM or tape, for distribution, it is necessary to use the -mc and/or -mo flags. Disk Distribution to End User by Mail-Order Disk Vendor. The defining properties of this medium include providing selected products (rather than a complete set, as on a CD-ROM) by mail, with or without a catalog from which to order. CD-ROM Distribution by CD-ROM, Tape, or Other Mass Media (except when used strictly within a BBS File Distribution Network). This form of distribution may target end users, BBS sysops, and/or other distributors. Since authors often restrict one or more of these specific targets, it is necessary to indicate if you are NOT selling to one or more of these, using the -mcb, -mcd, and/or -mcu flags. One-site Distribution by Single-Site Rack Vendor, by actual rack, shoebox, vending machine, diskettes on cardboard, or any other such mechanism. The essential idea is that shareware versions are made available on a physical medium via a single retail site. VendPrcs Processor v1.00 -26- Dec 1993 VendPrcs User's Guide Distribution Testing Rack Distribution to Retail Sites by Rack Distributor. This channel concerns those rack distributors who provide shareware products to multiple stores. The stores may or may not have a corporate connection to the distributor himself. The most important form of such distribution involves ready-made racks that are provided by the distributor for placement in the stores. Other similar forms are also included in this category. For example, there are CD-ROM-based vending machines now available for placement in retail stores. The essential idea here is that a distributor acts as a wholesaler to multiple stores, which sell individual copies of software packages directly to end users. Book Distribution in Book Enclosure Diskette. Subscription Distribution by Subscription Service. These are shareware services that distribute selected shareware packages to their subscribers, perhaps on a monthly basis. Magazine Distribution in Magazine Cover Diskette. TV Distribution by TV/Cable/Satellite, etc. This channel includes television broadcast, cable and satellite transmission, Videotex, and other similar means of distributing information. Phone Distribution by 1-900-Type Phone Service. Install Distribution by Installing in Customer's Machine. Some people like to distribute shareware products by actually installing them on the customer's machine. Prime examples are hardware dealers, who may "load up" their machines with software and consultants, who may be employed to help find the right software for the user, and to set it up to run. Undescribed Distribution by Other Methods than Covered Here. Charges Made for Distribution Services (-c) ------------------------------------------- Many shareware authors place limits on the amount of money that distributors may charge for the shareware (evaluation) versions of their products. The theory these authors are operating under is this: If the user has paid a large fee for the evaluation version, he will VendPrcs Processor v1.00 -27- Dec 1993 VendPrcs User's Guide Distribution Testing feel that he has already purchased the product, or that he is being abused by excessive charges. Such users probably don't register. The VENDINFO system handles such limitations as follows. The author specifies, for each distribution channel, the highest fee (in U.S. cents) allowed in each of the following categories: per product (self-explanatory) per 360K unit This covers both per-diskette charges by disk vendors and per-hour download charges by BBSes, telephone and TV/cable services, etc. per CD-ROM (if applicable) per year This covers subscription charges, by year, month, etc., to be a subscriber to a BBS, magazine, disk-vendor catalog, shareware subscription service, etc. The distributor then specifies the amount actually charged in each category, using the command-line options indicated below. All charges are expressed in U.S. cents (dollars times 100), regardless of the actual currency used (currency conversion tables are not generally available to VendPrcs at execution time). All volume-based charges are expressed in 360K units, regardless of the actual unit used. All subscription fees are expressed per year, regardless of the actual subscription period. -c0 Distributor will not charge users at all. This is equivalent to "-cc0 -ck0 -cp0 -cy0". -cc<amount> Charge per CD-ROM will not exceed amount (US cents) -ck<amount> Charge per 360K will not exceed amount (US cents) -cp<amount> Charge per product will not exceed amount (US cents) -cy<amount> Charge per year will not exceed amount (US cents) VendPrcs then compares the distribution policy with the proposed distribution, and "rejects" any distribution that would violate the product's distribution license. Notice that even zero chages must be indicated, since erroneous rejections can otherwise occur. Suppose, for example, that you run a BBS with a $50 annual subscription fee, and no other user charges. Suppose, further, that the product allows unlimited subscription fees, but places limits on single-product or volume-based download charges. If you fail to indicate that you do NOT make such charges, by including -ck0 -cp0 VendPrcs Processor v1.00 -28- Dec 1993 VendPrcs User's Guide Distribution Testing on the command line, VendPrcs will "reject" the distribution. Distributor "Type" (-t) ----------------------- In addition to information about a proposed distribution, information about the distributor itself can affect permission to distribute. Here are the relevant command-line options: -ta ASP member of appropriate member class -tc Consultant paid to select/evaluate/install products -th Hardware dealer bundling with hardware -tn Non-profit user group -tu User group Indicating Details of the Distribution Medium (-m) -------------------------------------------------- When physical media are used to distribute the products (diskettes, CD-ROMs, tapes, etc.), it is necessary to indicate some things about the media in order to verify that no author requirements are vio- lated. Here are the relevant flags: -mc<nontargets> CD-ROM (see below for info on "nontargets") -md Sysop sends diskettes to users -mh High-density diskette -mo Other (than CD-ROM) mass media (FDN only) For the CD-ROM distribution channel, the author may grant or withhold permission depending on the targetted market. Select these to indi- cate which you are NOT marketing to: b not marketed to Bbs sysops d not marketed to other Distributors u not marketed to end Users Thus, to describe a BBS-ready CD-ROM marketed to Sysops and disk vendors, but not to end users, you would include -mcu on the command line. VendPrcs Processor v1.00 -29- Dec 1993 VendPrcs User's Guide Distribution Testing Informing the Customer (-oi) ---------------------------- The way in which you present shareware to your customers is a major concern of many shareware authors. Various "sleazy" distributors have been known to "sell" shareware as if they owned the products, ignor- ing the authors' copyrights and failing to inform the customer of the nature of shareware. This practice hurts the whole industry, by o Discouraging users, who may view the author's registration request as a "bait-and-switch", and may avoid shareware altogether in the future. o Discouraging authors from distributing products via shareware channels. o Causing authors to restrict distribution to known, reliable distributors. In an effort to encourage distribution by the "good guys", the VEN- DINFO standard allows authors to give distribution permission to distributors who assert that they "fully inform" their customers. There are four parts to such full disclosure, and in order to qualify as a distributor under this provision, you must assert that you're clearly informing your customer of all four: s the product is Shareware. d the Definition/nature of shareware. o you claim no Ownership rights in the product. p separate Payment to author is required if used outside of author's evaluation terms. To assert that you comply with all four of these requirements, you should include the following on the VendPrcs command line: -oisdop Modifying or Bundling Packages (-om) ------------------------------------ Unless the command-line options indicate otherwise, it is assumed that the package will be distributed without modification. It is also assumed that it will be distributed separately from other products, unless mass media are involved. It you are planning to modify the package, or to bundle it with other similar or dissimilar products, you must indicate these intentions with the -om ("Modifications") option: VendPrcs Processor v1.00 -30- Dec 1993 VendPrcs User's Guide Distribution Testing -oma advertisement(s) will be Appended to existing document(s) -omb advertisement(s) will be added as separate file(s) -omc Compression method will be changed (e.g., ZIP to ARJ) -omd product will be bundled with Dissimilar products (e.g., a "starter set" for new users) -omh Help or GO.BAT will be added as separate files -omi Installation program or batch file will be added or changed -oms product will be bundled with Similar products (e.g., a "spreadsheet mega-disk" for comparisons) These options may be combined. For example, adding -ombchi to the command line would indicate that you intend to include ads as separate files, change the compression method, add a help or GO.BAT file, and add or change the installation program. Other Distribution Specifications (-o) -------------------------------------- See the two previous sections for "other" options dealing with o Modifying (or bundling) the author's package (-om) o Fully informing the customer (-oi) The remaining "other" options concern dealings between distributor and author, as follows: -oa package was received from Author or author's agent -oc author has been Contacted, this is current version -on will Notify author of distribution, version used -op have written Permission for proposed distribution -or agree to pay specified Royalties -os will send Sample materials to author Errorlevels Returned by Distribution Permission Tests ----------------------------------------------------- The following errorlevels are returned by VendPrcs as a result of distribution permission testing: Errorlevel Meaning 1 An error has occurred. This is probably an incorrect field code, but it might be VendPrcs Processor v1.00 -31- Dec 1993 VendPrcs User's Guide Distribution Testing due to other causes, in which case an error message should be written to stderr. 10 VENDINFO file has wrong size or CRC for either the text or data section, and may be a hacked or corrupted file. 11 VENDINFO file has missing or invalid author authentication codes, and may be a hacked or corrupted file. 20 A test of distribution permission has been requested, and the VENDINFO file prohibits distribution in the described way. 21 A test of distribution permission has been requested, and an executable in the package prohibits distribution in the described way. 30 A test of distribution permission has been requested, and the VENDINFO file allows distribution in the described way, but only if additional requirements are satisfied. 31 A test of distribution permission has been requested, and the VENDINFO file allows distribution in the described way, but only if written permission is obtained. 32 A test of distribution permission has been requested, and the VENDINFO file allows distribution in the described way, but only if additional requirements are satisfied AND written permission is obtained. 40 A test of distribution permission has been requested, and the VENDINFO file allows distribution in the described way. All conditions have been satisfied. It is a good idea to test for errorlevels 10 and 11 after the first VendPrcs command executed on a given VENDINFO file. Further tests for those particular errorlevels should be unnecessary. VendPrcs Processor v1.00 -32- Dec 1993 VendPrcs User's Guide Distribution Testing Testing for VENDINFO-Branded Executables ---------------------------------------- This is a planned capability not yet implemented. Testing for Altered Package Contents ------------------------------------ The VENDINFO.DIZ file includes a Packing List, with file names, dates, sizes, and CRCs for the files in the package as it was prepared by the author. To the degree that it can, VendPrcs will verify that the contents of the package are unchanged, or at least have not been altered in ways that violate the author's distribution license. This is easy when the author has specified that the package may not be altered, or that all original files must be included unchanged. Obviously, if the author has allowed more extensive changes, VendPrcs cannot reliably determine whether or not changes that may be present are violations of the author's distribution policy. The editor used by authors warns them that allowing such changes will disable this feature of the distribution policy testing. Unless this test is suppressed (see below), it will be performed automatically whenever a distribution policy test is done, and the presence of disallowed changes will result in rejection of the package. Suppressing Unwanted Testing (-n) --------------------------------- VendPrcs does several kinds of testing which you may wish to disable. We don't recommend it, but you're in charge. Disabling any of these tests may cause an erroneous "it's OK to distribute" result. Here are the options: -na Suppress author authentication and record validity testing (see later chapter, "Security"). -ne Suppress testing for VENDINFO-branded executables (see previous section, "Testing for VENDINFO-Branded Executables"). -nm Suppress testing for author-allowed modifications to package. This forces "Packing List" testing for an exact match, with no alterations whatsoever to the package. -np Suppress "Packing List" testing for changes that violate the product's distribution license (see previous section, VendPrcs Processor v1.00 -33- Dec 1993 VendPrcs User's Guide Distribution Testing "Testing for Altered Package Contents"). -nv Suppress "verbose" mode; results are written only to log file. VendPrcs Processor v1.00 -34- Dec 1993 VendPrcs User's Guide Package Routing +--------------------------------------+ | Package Routing and Disposition (-r) | +--------------------------------------+ In addition to testing for distribution permission, VendPrcs can also automate some of your package-handling operations. For example, VendPrcs can: o Rename the package to match the author's preference. o Move the package to a directory determined by the outcome of a distribution permission test. o Move the package to a directory determined by the product's primary category code. o Produce a list of packages rendered obsolete by the product's new version. o Automatically keep a separate library of VENDINFO files for easy reference. o Manage VendPrcs log files in several ways, depending on your preference. Before the individual package-handling operations are described, you need to understand the special directory arrangements that apply. Routing Directory Conventions ----------------------------- The operations discussed in the previous chapters need access to a single VENDINFO file, or to all the files extracted from a single "ZIP" or other compressed product package. In those cases, all of the files are assumed to be in the current working directory. The routing and log control options, however, may involve a number of direc- tories, whose actual pathnames are under your control. These direc- tories are: NeedPerm Directory into which VendPrcs may move packages for which written permission is needed and all other conditions of distribution are satisfied. NeedAddl Directory into which VendPrcs may move packages for which basic distribution conditions are satisfied, but some additional requirements must be assessed manually. VendPrcs Processor v1.00 -35- Dec 1993 VendPrcs User's Guide Package Routing NeedBoth Directory for packages requiring both written permis- sion and additional requirements. Invalid Directory into which packages may be moved if VENDINFO file is invalid or corrupted. Prohib Directory into which packages may be moved if the proposed distribution is prohibited. Approved Directory into which packages may be moved if all distribution requirements are satisfied. Reject Directory into which packages may be moved if rejected because of criteria set by you, such as products in categories in which you have no interest. Error Directory into which packages may be moved in any cases not covered above. Incoming Directory containing the still-compressed package whose VENDINFO file is under analysis. Logs Directory in which VendPrcs log files and obsolete- package lists are written. Library Directory into which VENDINFO files may be copied (under package names, as TESTR11.DIZ), for long-term retention. Temp Directory in which all required temporary files will be created. Not yet implemented. The actual directory paths corresponding to these functions are defined by you in the VPRESULT.CFG file located in the same directory as the invoked VENDPRCS.EXE. This file has one line per directory, containing the function name (from the list above) and the full pathname of the directory, as in Prohib C:\TOHANDLE\PROHIB Comment lines, beginning with a semicolon, are ignored. Package Filename (-p) --------------------- If VendPrcs is asked to move or rename the compressed package (from which the VENDINFO record was taken), it must know where to find the still-compressed package. This package cannot be assumed to be in the VendPrcs Processor v1.00 -36- Dec 1993 VendPrcs User's Guide Package Routing current working directory, since that would interfere with Packing List testing. If the package name is given as a simple filename, as in -p TESTR11.ZIP the package is assumed to be in the "Incoming" directory, as defined in the previous section. If the package name is given as a full pathname, as in these ex- amples: -p ..\TESTR11.ZIP -p .\TESTR11.ZIP -p C:\UPLOADS\TESTR11.ZIP then that pathname is used. Rename Package to Author-Indicated Name (-rn) --------------------------------------------- Sometimes -- especially in a BBS setting -- packages may have filenames other than the names preferred by the author. This can result in multiple copies of the same package, all with different filenames. The -rn ("reName") option allows you to force the package to be renamed as preferred by the author. To use this option, you must provide the package name using the -p option. This can be done along with a distribution permission test, or as a separate opera- tion. Consider, for example, vendprcs vendinfo.diz -p .\testr11.zip -rn This command assumes that the current working directory contains BOTH the package TESTR11.ZIP and a VENDINFO.DIZ file that has already been extracted from it. VendPrcs compares the author's preferred package filename prefix with the string "TESTR11" and, if different, renames TESTR11.ZIP to match the author's preference. When VendPrcs performs such a rename WITHOUT also doing a distribution permission test, the errorlevel returned indicates whether or not the package is now correctly named (errorlevel 50 indicates TRUE, and 51 indicates FALSE), or indicates an error (errorlevels 1, 10, or 11). See Appen- dix C for more information about errorlevels. When the -rn option is used along with a distribution permission test (-d), the renaming is done regardless of the outcome of the distribu- tion test, and has no effect on the returned errorlevel. VendPrcs Processor v1.00 -37- Dec 1993 VendPrcs User's Guide Package Routing Move Package Based on Test Outcome (-rm) ---------------------------------------- When a distribution test (-d) is done, VendPrcs can also be in- structed to move the original, still-compressed package based on the outcome of the test. (This also requires that the package name (-p) be given.) An example of such a command is vendprcs vendinfo.diz -db -c0 -rm -p ..\TESTR11.ZIP which would test for distributability of TESTR11.ZIP on a free BBS, and would move the package based on the result. The errorlevel returned would be that associated with the distribu- tion test. If the errorlevel is not 1 (error), the package is moved to one of the directories defined in the "Routing Directory Conventions" sec- tion, above. (A variation of this arrangement occurs when the -rc option is also used; see below.) The rename (-rn) option can be used along with -rm. Move Package Based on Product Category (-rc) -------------------------------------------- VendPrcs can also move packages based on the main product category encoded in the VENDINFO file. This is done using the -rc ("Category") option, which also requires use of the -p package-name option. Routing by category is controlled by the VPCATGRY.CFG file, located in the same directory as the invoked VENDPRCS.EXE. To understand this file, let's look first at part of the CATEGORY.INF file, 14000000 Business 14010000 Business finances 14010100 Business accounting 14010200 Point-of-sale systems 14010300 Billing systems 14010400 Purchase order systems 14010500 Payroll systems 14020000 Inventory systems ; 14030000 remaps to 14040100 ; 14030100 remaps to 14040101 14140000 Equipment use & maintenance 14040000 Project management VendPrcs Processor v1.00 -38- Dec 1993 VendPrcs User's Guide Package Routing 14040100 Project bidding & costing 14040101 Decision analysis tools 14040200 Project scheduling This file defines the category codes used in the VENDINFO system. As you can see, it has a hierarchic (tree) structure. The purpose of this file is to define that structure and to define the correspon- dence between the category codes and descriptive text. The VPCATGRY.CFG file has a similar hierarchic structure (perhaps greatly abbreviated), and maps the codes into directory pathnames, rather than descriptive text: ;14000000 Business 14000000 C:\BBSFILES\BUSINESS ; 14010000 Business finances 14010000 C:\BBSFILES\FINANCE ; 14010100 Business accounting ; 14010200 Point-of-sale systems ; 14010300 Billing systems ; 14010400 Purchase order systems ; 14010500 Payroll systems ; 14020000 Inventory systems ; 14030000 remaps to 14040100 ; 14030100 remaps to 14040101 ; 14140000 Equipment use & maintenance ; 14040000 Project management 14040000 C:\BBSFILES\PROJMAN ; 14040100 Project bidding & costing ; 14040101 Decision analysis tools ; 14040200 Project scheduling This example would move all "Business" packages in the BUSINESS directory, except for those dealing with finance (the FINANCE direc- tory) or project management (PROJMAN). As the example illustrates, whole subtrees of the category structure can be mapped into a single directory. This allows many categories to be omitted or commented out. Thus, you might wind up with only a few lines, mapping all the games categories to one directory, all business to another, etc. You can also "reject" a category by placing the word "Reject" where the directory pathname would otherwise appear. This will cause packages in that category to be moved to the "Reject" directory defined in VPRESULT.CFG. VendPrcs Processor v1.00 -39- Dec 1993 VendPrcs User's Guide Package Routing Here's a possible complete VPCATGRY.CFG file for a distributor inter- ested only in games: 00000000 Reject 07000000 c:\games Because this file defines an action for the "root" node of the category tree (category 00000000), it defines correct behavior for all possible category nodes. Thus, a product in category 07010000 would be moved to the games directory, since 07010000 is a sub- category under 07000000, while a product in category 01000000 would be rejected. There are two ways to use the -rc option. If it is used along with both the -d and -rm options, as in vendprcs vendinfo.diz -db -c0 -rcm -p TESTR11.ZIP then packages are moved based on the result of the distribution test, and only those packages that would have gone to the "Approved" direc- tory are moved by category. All others are moved as if only -rm were selected, rather than -rcm. A package whose main category code is not covered by the VPCATGRY.CFG file is moved to the "Approved" direc- tory. Errorlevels are those associated with the distribution test (- d). If package movement by category is done as a stand-alone operation, vendprcs vendinfo.diz -c0 -rc -p TESTR11.ZIP then the package is moved as indicated based on its category code and the VPCATGRY.CFG file. A package whose main category code is not covered by the VPCATGRY.CFG file is not moved. Errorlevels are 1, 10, or 11 for errors, 50 (TRUE) if package is moved, or 51 (FALSE) if package is not moved. The rename (-rn) option can be used along with -rc or -rcm. VendPrcs Processor v1.00 -40- Dec 1993 VendPrcs User's Guide Package Routing Logs and Generated Lists (-rl -rs -rd -ro) ------------------------------------------ The logs produced by VendPrcs during distribution testing and package routing can be very informative. NOTE: The actual output format will be completely redesigned for the next round of beta testing. Here's an example: VendPrcs 1.00 Copyright 1993 Rams' Island Software, Parker, CO USA UNREGISTERED COPY: If used past 30-day evaluation period, registration is required. Registration is free for single-line, strictly non-commercial BBSes. Testing: C:\RUDY\SWDEV\VENDINFO\VENDEDIT\INCXT11A\VENDINFO.DIZ InContext Work Environment Manager v1.10 Rams' Island Software for: Distribution to End User by Mail-Order Disk Vendor Contents checked against Packing List for ALLOWED CHANGES but not: VENDINFO record(s) not checked for authenticity/validity Mods: Author requires *all* original, unchanged files be present Entire package is as released by author Quals: Would "qualify" if ASP distributor member [-ta] Would "qualify" if customer fully informed [-oipods] Would "qualify" if user group [-tu] Would "qualify" if non-profit user group [-tn] Would "qualify" if package was received from author [-or] Disqual: Charge per product not <= US$ 10.00 [-cp<amt>] Charge per 360K not <= US$ 10.00 [-ck<amt>] (Eliminating disquals removes requirement for permission) Note: All rights not expressly granted are reserved to the author. The author may revoke any permissions granted here, by notifying you in writing. AddlReq: Written permission is required, and not obtained [-op] DISTRIBUTION WOULD BE ALLOWED if written permission obtained These logs can be produced in any (or all) of several ways, depending on the command-line options. no -nv A log is written to standard output, which is usually the screen, but can be redirected to a file. The -nv (no verbose) option suppresses this output. VendPrcs Processor v1.00 -41- Dec 1993 VendPrcs User's Guide Package Routing -rl A single main log, VENDPRCS.LOG, is maintained, and each new VendPrcs invocation appends log information to that log. A "Logs" directory must be defined in VPRESULT.CFG. -rs A separate log is created for the individual package, and saved by a name like TESTR11.LOG in the "Logs" directory defined by VPRESULT.CFG. If the package is renamed using the -rn option, the log name is also adjusted. -rd When used with -rm and/or -rc, a separate log is produced and placed in the directory to which the package is moved, with name adjusted if -rn is also used. In the event that the package is not moved, and -rs is not also selected, the log is placed in the "Logs" directory as if -rs were selected. Some of these options require production of a temporary log, which is moved, copied, or renamed as appropriate. This temporary file will be TEMPLOG.LOG in the "Logs" directory. One special list can be produced to assist the distributor (others are under consideration). These files are placed in the "Logs" direc- tory. -ro OBSOLETE.LST, a list of packages possibly rendered obsolete by the current version. Maintain VENDINFO File Library (-rv) ------------------------------------ If this option is selected, a copy of the VENDINFO file will be saved in the "Library" directory, using the author's indicated filename prefix. Thus, the VENDINFO.DIZ file from the TESTR10 package would be saved as TESTR10.DIZ. VendPrcs Processor v1.00 -42- Dec 1993 VendPrcs User's Guide Security +----------+ | Security | +----------+ The security features of VENDINFO make no claim to be hack-proof, but they should be sufficient to: o Eliminate manual editing of VENDINFO records, which could do serious accidental or deliberate damage. o Eliminate casual hacking. o Require effort on the part of a serious hacker that exceeds any likely gain. Some of the security features in the initial release of VENDINFO are: o The structure, complexity, and internal checks associated with the VENDINFO record are such that it is difficult to produce without a specialized VENDINFO editor. o The editor cannot edit a distributed VENDINFO file. It produces such files from an intermediate file -- which the author keeps -- in a one-way operation. o Both the text and data portions of the VENDINFO records are checked for size and CRC. o VENDINFO records can contain two "authentication" keys that help verify the source and unaltered content of the record. o The editor will produce "authenticated" VENDINFO records only in the presence of an author-specific key that is not con- tained in the distributed VENDINFO record. Planned capabilities for a subsequent VENDINFO release include: o If the author chooses, an abbreviated VENDINFO record can be embedded in any or all executable programs. This insures that basic identification and distribution policy information is present and automatically testable even if the VENDINFO record is removed from the distribution package. o If the author chooses, the executable VENDINFO record can require the presence of a specific VENDINFO file (identified by a CRC-like value). This would allow automatic detection of the removal of the VENDINFO file from the distribution VendPrcs Processor v1.00 -43- Dec 1993 VendPrcs User's Guide Security package. It would also allow automatic detection of the substitution of a VENDINFO file in the distribution package even if the file itself passed all security checks. o If the author places the executable VENDINFO record inside his/her own protective CRC envelope, a complete understanding of the VENDINFO security scheme would not be enough to defeat it. A hacker would also have to defeat the author's own security layer. o A separate mechanism exists which allows a central site (the Product Registry) to verify the authenticity of a VENDINFO record based on private keys. o A provision for author tracking brands in the uncompressed front-text of the VENDINFO.DIZ file. These brands will be visible to a file viewer, easily accessible to the author's own software, and defended against modification by in- dividuals other than the author. VendPrcs Processor v1.00 -44- Dec 1993 VendPrcs User's Guide Examples +------------------------------------+ | Putting It All Together (Examples) | +------------------------------------+ This chapter will present a variety of simple example applications of VendPrcs. It is unlikely that any of these examples will match your situation exactly, but they should help you understand the many things VendPrcs can do. Force Package to Author-Preferred Name -------------------------------------- To force a ZIP package to the author's indicated package name, you might use this simple batch file: rem Assumes PACKAGE.ZIP is in current, working directory del *.diz pkunzip package.zip vendinfo.diz if not exist vendinfo.diz goto after vendprcs vendinfo.diz -rn -p .\package.zip if errorlevel 51 goto error if errorlevel 50 goto after :error ... :after VendPrcs Processor v1.00 -45- Dec 1993 VendPrcs User's Guide Examples A Low-Maintenance Games-Only BBS -------------------------------- The Games Haven BBS is a free ASP-member BBS specializing in games. The sysop wants to minimize the time he spends on the BBS, so he posts only games that are distributable without written permission or special handling. If allowed, he repackages all games in ZIP form, in which case he also adds a GAMHAVEN.BBS advertisement, if that is allowed. It is assumed that a file-upload processor has already unpacked the compressed package into the current working directory and done any necessary virus checking. A possible batch file for this situation is GAMHAVEN.BAT in EXAMPLES.ZIP. Briefly, the batch file tests for distributability by this particular BBS without written permission or other special conditions: vendprcs vendinfo.diz -db -c0 -ta if errorlevel 40 goto bbsok if errorlevel 20 goto reject goto reject checks to see whether or not repackaging as a ZIP is OK vendprcs vendinfo.diz -egmc if errorlevel 51 goto use_orig adds a GAMHAVEN.BBS advertisement if allowed vendprcs vendinfo.diz -egmas if errorlevel 51 goto no_ad copy c:\mystuff\gamhaven.bbs repackages the whole affair as TEMP.ZIP or uses the original package, and moves the resulting package to the appropriate file area or to a reject bin based on its product category. For example: vendprcs vendinfo.diz -p %1 -rcn This requires a VPCATGRY.CFG file that might look something like this: 00000000 Reject 07130000 c:\games\advent 07060000 c:\games\arcade 07210000 c:\games\board 07070000 c:\games\card ... 07990000 c:\games\other VendPrcs Processor v1.00 -46- Dec 1993 VendPrcs User's Guide Examples BBS-Ready CD-ROM Production --------------------------- In this example, a CD-ROM publisher wishes to select, from a large set of programs, all those that satisfy two criteria: o Distribution by BBS is totally unlimited. o Distribution on a $40 CD-ROM is allowed, possibly subject to additional requirements. The result will be a candidate set of programs for a CD-ROM that can be sold strictly to BBS sysops, for on-line access via BBS. A complete batch file for this example is BBSCDROM.BAT in EXAMPLES.ZIP. Please note that this batch file has not yet been tested (fix HERE). The batch file leaves a copy of the package in one of several directories, as defined in the batch file itself and in VPRESULT.CFG, along with a correspondingly named LOG file. While the complete batch file is too large for inclusion here, the working part of the batch file is rather short and simple: pkunzip %1 vendinfo.diz if not exist vendinfo.diz goto manual rem ----- reject BBS-limited products -------------------------- vendprcs vendinfo.diz -db if errorlevel 40 goto bbsok if errorlevel 20 goto reject goto bad_vendinfo :bbsok rem ----- now test for CD-ROM distributability ----------------- vendprcs vendinfo.diz -dc -cc40 -mcb -rmnd -p .\%1 goto done VendPrcs Processor v1.00 -47- Dec 1993 VendPrcs User's Guide Examples Build FILES.BBS --------------- This example constructs a file description of the sort typically used in BBS FILE.BBS lists. Here's an example of such a description, truncated on the right to fit here: INCXT11D.ZIP 216251 1/31/93 InContext(TM) Work Environment Mana Part 1 of 2 <ASP>. Complete Work En Manager for expert PC users. Automa aspects of the PC user's work than product. Designed by a PhD ergonomi based on fundamental principles of actually work. Much more than a DOS NEW VERSION 1.10 has Gantt charts, tagging, 4DOS long descriptions, PK support, *many* new features. FILESBBS.BAT (in EXAMPLES.ZIP) is a complete batch file to produce these descriptions. Here's the working part of a similar batch file, to illustrate the basic approach: vendprcs -xxpf -zw12 -zn -p .\INCXT11D.ZIP > OUTPUT vendprcs -zl -xxps -zw8 -zn -p .\INCXT11D.ZIP >> OUTPUT vendprcs -y " " -zn >> OUTPUT vendprcs -xxpd -zw9 -zn -p .\INCXT11D.ZIP >> OUTPUT vendprcs VENDINFO.DIZ -xpd4 -zi31 -zc45 -y " @" >> OUTPUT VendPrcs Processor v1.00 -49- Dec 1993 VendPrcs User's Guide Examples Automatic Permission Request ---------------------------- This example shows automated production of a letter to an author from a disk vendor, describing the vendor's company and requesting permis- sion to distribute the author's product. It is also possible to automatically construct electronic mail messages in this way. A complete batch file for this purpose is REQUEST.BAT in EXAMPLES.ZIP. Here's a segment of the batch file, to illustrate the idea. This batch file produces a text file (LETTER.TXT) suitable for use with Ventura Publisher to print the letter on existing company letterhead. vendprcs %1 -xac -y "@@AUTHOR = @" > letter.txt vendprcs -y " " >> letter.txt vendprcs %1 -xaa -y "@@ADDRESS = @" -zv >> letter.txt vendprcs -y " " >> letter.txt echo Dear Author: >> letter.txt vendprcs -y " " >> letter.txt echo We have recently received a copy of your >> letter.txt vendprcs %1 -xpp -y "<B>@" -zn >> letter.txt vendprcs %1 -xpe -zn >> letter.txt vendprcs %1 -xpv -y "v@<D>." >> letter.txt vendprcs -y " " >> letter.txt echo We are quite interested in adding this >> letter.txt echo program to our inventory, but we observe >> letter.txt echo that you require written permission... >> letter.txt vendprcs -y " " >> letter.txt echo This letter will serve to introduce you >> letter.txt echo to our business, and... >> letter.txt vendprcs -y " " >> letter.txt echo @CLOSING = Yours truly, >> letter.txt vendprcs -y " " >> letter.txt vendprcs -y "@SIGNATURE = Ima D. Vendor" >> letter.txt A similar application of these techniques could produce a catalog entry for a disk vendor's mail-order catalog. VendPrcs Processor v1.00 -50- Dec 1993 Appendix A Command-Line Arguments +-----------------------------------------------+ | Appendix A -- VendPrcs Command-Line Arguments | +-----------------------------------------------+ VendPrcs is invoked from the command line in the following way: vendprcs <filename> [options] where [options] can be as follows ("-" can be replaced by "/") Charges by distributor: -c0 Distributor will not charge users at all -cc<amount> Charge per CD-ROM will not exceed amount -ck<amount> Charge per 360K will not exceed amount -cp<amount> Charge per product will not exceed amount -cy<amount> Charge per year will not exceed amount Distribution testing: -db Test distribution permission (Bbs channel) -dd Test distribution (mail-order Disk vendor) -dc Test distribution (Cd-rom) -df Test distribution (bbs File-distrib net) -di Test distribution (Installation by distrib) -dk Test distribution (booK enclosure diskette) -dm Test distribution (Magazine cover diskette) -do Test distribution (One-site rack vendor) -dp Test distribution (1-900-type Phone service) -dr Test distribution (multi-site Rack distrib) -ds Test distribution (Subscription service) -dt Test distribution (Tv/cable/satellite/...) -du Test distribution (Undescribed method) Existence testing for field values: -e<code> Test field for existence of value (See Appendix B for codes) Medium of distribution: -mc<nontargets> CD-ROM b = not marketed to Bbs d = not marketed to Distributor u = not marketed to User -md Sysop sends diskettes to users -mh High-density diskette -mo Other (than CD-ROM) mass medium No testing of specified things: -n<tests> Suppress testing for indicated things a No author authentication VendPrcs Processor v1.00 -51- Dec 1993 Appendix A Command-Line Arguments e No executables testing (future version) m No test for author-allowed mods p No Packing List testing v No verbose mode, write only log Other assertions about distribution: -oa Package was received from author -oc Author contacted, is current version -oi<statements> Informs customer as indicated d Shareware defined o Not owner of product p Payment to author required s Product is shareware -om<mods> Proposed modifications/bundling a Ads appended to existing docs b Ads added as separate files c Change compression (e.g., ZIP to ARJ) d Bundle with dissimilar products h Help or GO.BAT added as separate file i Change installation program s Bundle with similar products -on Notifying author of distribution, version -op have written Permission from author -or Agree to pay specified royalties -os Sending author distribution sample Package name: -p <package_name> File or pathname of compressed package Routing and Log-Control Operations: -r<operations> c Move package based on product category d Produce distributed logs with packages m Move package based on test outcome n Rename package to author-indicated name o Produce obsolete-package list l Keep master Log of all VendPrcs operations s Keep separate logs by package v Keep VENDINFO files in long-term library Special output formats: -s<type> See documentation Type of distributor: -t<types> Distributor types a ASP member of appropriate member class c Consultant paid for eval and install h Hardware dealer bundling with hardware n Non-profit user group VendPrcs Processor v1.00 -52- Dec 1993 Appendix A Command-Line Arguments u User group Entering User registration information: -u "<company name>" <serial number> <key> Extraction of field values: -x<code> Extract field value (See Appendix B for codes) Label string for extractions: -y <label string> Output this literal string with value Other extraction specifications: -zc<columns> Maximum width of output -zd <format string> Format for date, price (note space) -zf <FALSE string> String to output if TRUE (note space) -zi<indentation> Indentation amount -zk Keep VENDDATA file for re-use -zl Pad on left, if necessary (with -zw) -zn Suppress newline in output -zr<rows> Maximum height of output -zt <TRUE string> String to output if FALSE (note space) -zv Produce Ventura embedded <R> codes -zw<width> Exact width of output (pad/truncate) VendPrcs Processor v1.00 -53- Dec 1993 Appendix B: Field Codes Author +------------------------------------+ | Appendix B -- Field Code Reference | +------------------------------------+ Author/Publisher Information ---------------------------- aa Author/company address ac Company name Author/Publisher Electronic Addresses aea America OnLine user ID aeb BBS phone number aec CompuServe Information System user ID aed Delphi user ID aef FidoNet node number aeg Genie user ID aei Internet address aen BBS name aeo Other electronic addresses aep Prodigy user ID aer RIME node address aeu BBS username for mail when using BBS af Author facsimile (FAX) phone number Membership in Trade Associations ama Association of Shareware Professionals (ASP)? amb Association of Shareware Authors and Distributors (ASAD)? amd Deutschsprachige Shareware Authoren und Haendlervereinigung? ame Educational Software CoOperative? amp Software Publishers' Association (SPA)? ams Shareware Trade Association and Resources (STAR)? amx Other trade association memberships? an Author name (personal name) ap Author voice phone number aq Product queries phone number Channel-Specific Distribution Information ----------------------------------------- These Channel Identification Letters Are Used in Field Codes Below b = Bbs f = bbs File-distribution network VendPrcs Processor v1.00 -54- Dec 1993 Appendix B: Field Codes Distribution d = mail order Disk vendor c = Cd-rom o = One-site rack vendor r = multi-site Rack distributor k = booK enclosure disk s = Subscription service m = Magazine t = Television/cable/satellite and similar p = 1-900 Phone distribution or similar i = Installation by distributor on end-user's machine u = other method Undescribed by above Distribution Field Codes d?a Additional distribution requirements (text) d?dc Price limit per CD-ROM (if turned on) d?dd Date after which distribution is prohibited d?dk Price limit per 360K (if turned on) d?dp Price limit per product (if turned on) d?dt Date after which distributor must contact author d?dy Price limit per year (if turned on) d?ma Any distributor qualifies? d?maa Any distributor who is an ASP member qualifies? d?mac Any consultant qualifies? d?mad Any full-disclosure distributor qualifies? d?mah Any hardware dealer qualifies? d?man Any non-profit user group qualifies? d?maq Additional requirements specified in this data record? d?mar Distributor receiving product from author qualifies? d?mau Any user group qualifies? d?mdc Distributor must check if after contact date? d?mdp Distribution is prohibited after prohib date? d?mh Diskette distribution on high-density media only? d?mna Distributor disqualified if any charge is made to user? d?mnb If target market is BBS, distribution is not allowed? d?mnc Disqualified if charge per CD-ROM exceeds amount? d?mnd If distributor "disqualified", distribution prohibited? d?mng If target is distributors, distribution not allowed? d?mnk Disqualified if charge per 360K exceeds amount? d?mno Disqualified if distributing by other mass media? d?mnp Disqualified if charge per product exceeds amount? d?mpq "Qualified" distributors need written permission?? d?mnr Disqualified if distributing by CD-ROM? d?mnu If target is end users, distribution not allowed? d?mny Disqualified if charge per year exceeds amount? d?mp Distribution by this channel is prohibited? d?mpd If "disqualified", written permission is required? d?mr Royalties must be paid for distribution? d?msq Sample of distribution materials is requested? d?msr Sample of distribution materials is required? VendPrcs Processor v1.00 -55- Dec 1993 Appendix B: Field Codes Distribution d?mst Must see front text for additional requirements? d?mv Notification of dist and version number is required? Human-Readable Front Text Sections ---------------------------------- ff Packing List (files) section from front text fi Installation section from front text fl License section from front text fp Product Information section from front text fr READ-ME section from front text fs<n> Special section number n (1-9) from front text fv VENDINFO description at beginning of file fw Warranty section from front text Channel-Independent ("General") Distribution -------------------------------------------- gc Additional limitations on using different compressor gd Restrictions on bundling with dissimilar products gg Other geographic restrictions on distribution gh Other information about allowed changes to package gi Other restrictions on changing installation procedure gmaa Ads may be appended to existing documentation files? gmas Ads may be added as separate files? gmc Package may be repackaged with different compressor? gmct See front text for add'l restrictions on recompression? gmd OK to bundle with dissimilar products (e.g., starter set)? gmdp Written permission required for bundling with dissimilar? gmdt Text has add'l requirements on bundling with dissimilar? gmf Must all original files be included in unmodified form? gmhs Can add a help file, GO.BAT, etc. as a separate file? gmi Can add or substitute an installation procedure? gmit Text has add'l requirements on changing installation? gmp Distributable only in original unmodified form? gms OK to bundle with similar products (e.g., "mega-disk")? gmsp Written permission required for bundling with similar? gmst Text has add'l requirements on bundling with similar? gmu Distribution outside U.S. illegal, contained encryption? gs Restrictions on bundling with other, similar products gt Product distribution category gu Author's policy on providing upgrades to distributors VendPrcs Processor v1.00 -56- Dec 1993 Appendix B: Field Codes Header VENDINFO Header Information --------------------------- hd VENDINFO file preparation date ht VENDINFO file type hv Version number of VENDINFO file itself Price and Benefits Information ------------------------------ ic Currency in which prices are expressed imd Dealer discounts available? ime Dealer discount prices are in attached text? iml Low-cost retail (LCR) version of product available? imn Enhanced non-shareware version (NSV) available? imp Royalty rates are included in attached text? imq Royalties are negotiated on a case-by-case basis? imr Royalties required for some forms of distribution? ims Site licenses are available for product? imt Site license rates are included in attached text? ira Royalty agent for author (contact author first) irm Minimum royalty, when royalties apply to channel irn Text description of when minimum royalty applies irx Maximum royalty, when royalties apply to channel iry Text description of when maximum royalty applies Shipping and Handling Charges isa Asia isc within-country ise Europe isf Africa isn North America isp Pacific Rim iss South America Registration Benefits (1=minimum, 2=maximum) i?bad Additional data files? i?bap Additional programs? i?bbs BBS or other online support? i?bbr Branding with user's name? i?bbu Bug notices? i?bcc Cheat codes? i?bcm Commissions? i?bcn Contests? i?bcu Customization (screens, printouts, etc.)? i?bcr Data conversion utilities (for other programs)? i?bcx Data conversion utilities (from older versions)? VendPrcs Processor v1.00 -57- Dec 1993 Appendix B: Field Codes Prices i?bdi Discounts on other programs, merchandise, etc.? i?ben Enhanced program functionality (*)? i?bfg Free goodies? i?bfu Future versions (license for continued use)? i?bgu Guarantee? i?bhi Hints (hint book, application notes, etc.)? i?bla Latest version? i?bls Lifetime support? i?bne Newsletter? i?bpp Preprinted forms? i?bpm Printed manual? i?bqr Quick reference cards, keyboard templates, etc.? i?brl Record limitation removal (*)? i?bre Registration-Reminder-Screen removal? i?brd Repeated delay screen or slowdown removal (*)? i?bsd Sample data files, templates, examples, etc.? i?bso Source code? i?bsu Subscription to updated data? i?btl Time-limit removal (*)? i?btu Tutorial for use of product? i?bun Update notices? i?buf Updates free? i?bvs Voice telephone support? i?bwa Watermark removal? i?p Registration price of product i?v Other registration benefits Ordering Information -------------------- oa Order address (includes author/company name) ob Order bank and bank account information Credit Cards Accepted oca American Express (and Optima) cards accepted? occ Diner's Club credit cards accepted? ocd Discover credit cards accepted? oce Access/Eurocard credit cards accepted? ocm MasterCard credit cards accepted? ocv Visa credit cards accepted? ocx Order credit cards accepted Electronic Addresses for Ordering oea America OnLine user ID oeb BBS phone number oec CompuServe Information System user ID oed Delphi user ID VendPrcs Processor v1.00 -58- Dec 1993 Appendix B: Field Codes Ordering oef FidoNet node number oeg Genie user ID oei Internet address oen BBS name oeo Other electronic addresses oep Prodigy user ID oer RIME node address oeu BBS username for mail when using BBS of Order facsimile (FAX) phone number oo Other sources of registered version op Order voice phone number (not toll-free) Accepted Forms of Payment (other than credit cards) oxa Payment accepted by American Express money order? oxbh Bank check from sender's country, in hard currency? oxbo Bank check in other (typically soft) currency accepted? oxbr Bank check, hard currency, on bank in recip country? oxbs Bank check recipient's currency, bank in recip country? oxch Payment in cash, hard currency other than recipient's? oxco Payment in cash, other (typically soft) currency? oxcs Payment in cash, recipient's currency? oxd Payment by direct (electronic) bank funds transfer? oxe EuroCheque, recipient's currency, guarantee card nbr on back? oxmi Payment by international postal money order? oxms Payment by postal money order issued in recipient's country? oxoh Purchase orders accepted in hardcopy from most major firms? oxon Purchase orders accepted by purchase order number? oxph Personal check in sender's hard currency from sender's bank? oxpo Personal check in other (typically soft) currency accepted? oxpr Personal check in hard currency, bank in recip country? oxps Personal check recipient's currency, bank in recip country? oxto Traveller's check from other than recipient's country? oxts Traveller's check from recipient's country? oxx Order other acceptable funds ot Order toll-free phone, if any Product Information ------------------- pc? Product category (there are five, numbered 1-5) Product Descriptions pd Product description (longest to fit within size limits) pd1 Product description (one-line) pd2 Product description (two-line) pd3 Product description (250-char) VendPrcs Processor v1.00 -59- Dec 1993 Appendix B: Field Codes Product pd4 Product description (450-char) pd5 Product description (750-char) pd6 Product description (1500-char) pe Product name extension or category name Platform, Scanners pfaf Hewlett-Packard or compatible flatbed scanner pfag Genius scanner or compatible pfal Logitech hand scanner or compatible Platform, Configuration pfcf Floating-point unit (FPU) pfcl Laptop pfcm Micro Channel Adapter Platform, Disk Drive pfdc CD-ROM drive pfdf Floppy only pfdh Hard drive Platform, Input Devices pfid Digitizer pfij Joystick pfik Keyboard pfim Mouse Platform, Modem pfma Any serial modem pfmf Fax/modem pfmh Hayes-compatible serial modem Platform, Network pfne Network Platform, Ports pfoc PCMCIA pfog Game pfop Parallel pfos Serial Platform, Printer pfpd Hewlett-Packard Deskjet printer pfpe Epson 9-pin printer or compatible pfpf Epson 24-pin printer or compatible pfpi IBM Graphics Printer pfpl Hewlett-Packard Laserjet printer pfpo Plotter pfpp Hewlett-Packard Paintjet printer VendPrcs Processor v1.00 -60- Dec 1993 Appendix B: Field Codes Product pfps Postscript printer pfpt Text printer (specific types may be shown below) pfpy Printer (specific types may be shown below) Platform, Memory (RAM) pfre Extended Memory pfrh HIMEM pfrm EMS Memory pfro Expanded *or* Extended Memory pfrx XMS Memory Platform, Sound Boards pfsa AdLib sound card pfsb Sound Blaster sound card pfsc Covox sound card pfsm Musical Instrument Digital Interface (MIDI) pfsy Sound card (specific types may be shown below) Platform, Video pfv8 IBM 8514 Adapter pfva Monochrome monitor pfvb Color monitor pfvc Color Graphic Adapter (CGA) pfve Enhanced Graphic Adapter (EGA) pfvh Hercules Graphics Card pfvm Monochrome Display Adapter (MDA) pfvn Multi-Color Graphics Array (MCGA) pfvo Multi-Color Graphics Array 256 (MCGA 256) pfvs Other Super VGA (SVGA, other) pfvt Tandy Display Adapter pfvv Video Graphics Array (VGA) pfvw VESA Super VGA (SVGA, VESA) pfvx XGA ph Screen shot support format list (e.g., 'PCX CGM FLM') pk List of suggested keywords describing product pn Product filename prefix (without 'A', 'B' for multipart) po Other platform requirements pp Product name (e.g., 'Wordstar') without category or version Product Package Names and Related Information ppc List of CompuServe (6-char) package prefixes ppl List of package prefixes (e.g., 'MYPKGA MYPKGB') ppn Number of packages making up full product (how many ZIPs) ppt Filename prefix of this package pr Reason for existence of this version ps Description of other software required to use this product pt Product version release date VendPrcs Processor v1.00 -61- Dec 1993 Appendix B: Field Codes Product pv Version number of product, without 'V' (e.g., '1.10') px List of filename prefixes for previous versioms now replaced py Product type (e.g., software) Basic Platform Information (1=minimum, 2=recommended) p?c Platform: CPU p?dm Platform: Disk Space (Kbytes), minimal installation p?df Platform: Disk Space (Kbytes), full installation p?o Platform: Operating System p?re Platform: Extended Memory (Kbytes) p?rm Platform: EMS Memory (Kbytes) p?rs Platform: Standard (low) Memory (Kbytes) p?rx Platform: XMS Memory (Kbytes) p?s Platform: Clock Speed (MHz) Information about Distributors of Registered Version ---------------------------------------------------- Distributor Information (# = 1, 2, ... for multiple distributors) r#a Distributor address (includes name) r#c Currency in which prices are expressed Credit Cards Accepted (valid only if enabled; test r#mc) r#ca American Express (and Optima) cards accepted? r#cc Diner's Club credit cards accepted? r#cd Discover credit cards accepted? r#ce Access/Eurocard credit cards accepted? r#cm MasterCard credit cards accepted? r#cv Visa credit cards accepted? r#cx Order credit cards accepted r#f Facsimile (FAX) phone number Prices for Registered Version r#i1 Minimum registration price r#i2 Minimum registration price Shipping and Handling Charges r#sa Asia r#sc within-country r#se Europe r#sf Africa r#sn North America r#sp Pacific Rim r#ss South America Miscellaneous Distributor Flags r#ma Author drop-ships product VendPrcs Processor v1.00 -62- Dec 1993 Appendix B: Field Codes Registered Dist r#mc Credit card and funds enabled for this distributor r#md Handles other distributors in region r#mj Handles press in region r#mo Sole source of technical support in region r#mp Prices enabled for this distributor r#ms Handles technical support in region r#p Voice phone number r#r Geographical region covered r#t Toll-free voice phone number, if any Accepted Forms of Payment (valid only if enabled; test r#mc) r#xa Payment accepted by American Express money order? r#xbh Bank check from sender's country, in hard currency? r#xbo Bank check in other (typically soft) currency accepted? r#xbr Bank check, hard currency, on bank in recip country? r#xbs Bank check recipient's currency, bank in recip country? r#xch Payment in cash, hard currency other than recipient's? r#xco Payment in cash, other (typically soft) currency? r#xcs Payment in cash, recipient's currency? r#xd Payment by direct (electronic) bank funds transfer? r#xe Payment by EuroCheque, guarantee card number on back? r#xmi Payment by international postal money order? r#xms Payment by postal money order issued in recipient's country? r#xoh Purchase orders accepted in hardcopy from most major firms? r#xon Purchase orders accepted by purchase order number? r#xph Personal check in sender's hard currency from sender's bank? r#xpo Personal check in other (typically soft) currency accepted? r#xpr Personal check in hard currency, bank in recip country? r#xps Personal check recipient's currency, bank in recip country? r#xto Traveller's check from other than recipient's country? r#xts Traveller's check from recipient's country? Technical Support Information ----------------------------- sa Support address (includes author/company name) Support Electronic Addresses sea America OnLine user ID seb BBS phone number sec CompuServe Information System user ID sed Delphi user ID sef FidoNet node number seg Genie user ID sei Internet address sen BBS name seo Other electronic addresses VendPrcs Processor v1.00 -63- Dec 1993 Appendix B: Field Codes Support sep Prodigy user ID ser RIME node address seu BBS username for mail when using BBS sf Support facsimile (FAX) phone number sp Support voice phone number ss Electronic forums on which product is supported Special Information Not From Inside VENDINFO Record --------------------------------------------------- xd Current date xh Full path of current working directory Information about compressed package (-p) xpd Package date xpe Package filename extension xpf Package filename xph Full path of directory containing package xpl Full path of package xps Package size xpx Package filename prefix Information about VENDINFO file xpd File date xpe Filename extension xpf Filename xph Full path of directory containing file xpl Full path of file xps File size xpx Filename prefix VendPrcs Processor v1.00 -64- Dec 1993 Appendix C VendPrcs Errorlevels +------------------------------------+ | Appendix C -- VendPrcs Errorlevels | +------------------------------------+ The following errorlevels are returned by VendPrcs: Errorlevel Meaning 0 No operation requested. 1 An error has occurred. This is probably an incorrect field code, but it might be due to other causes, in which case an error message should be written to stderr. 10 VENDINFO file has wrong size or CRC for either the text or data section, and may be a hacked or corrupted file. 11 VENDINFO file has missing or invalid author authentication codes, and may be a hacked or corrupted file. 20 A test of distribution permission has been requested, and the VENDINFO file prohibits distribution in the described way. 21 A test of distribution permission has been requested, and an executable in the package prohibits distribution in the described way. 22 VendPrcs has been asked to move package by product category, and the user has flagged this product's category as a "Reject". 30 A test of distribution permission has been requested, and the VENDINFO file allows distribution in the described way, but only if additional requirements are satisfied. 31 A test of distribution permission has been requested, and the VENDINFO file allows distribution in the described way, but only if written permission is VendPrcs Processor v1.00 -65- Dec 1993 Appendix C VendPrcs Errorlevels obtained. 32 A test of distribution permission has been requested, and the VENDINFO file allows distribution in the described way, but only if additional requirements are satisfied AND written permission is obtained. 40 A test of distribution permission has been requested, and the VENDINFO file allows distribution in the described way. All conditions have been satisfied. 50 A test for existence of a field value (or certain other tests) has been requested, and the result is TRUE. 51 A test for existence of a field value (or certain other tests) has been requested, and the result is FALSE. 52 Extraction of a field value has been requested, and performed successfully (return of "(none)" for a missing value is regarded as a success). It is a good idea to test for errorlevels 10 and 11 after the first VendPrcs command executed on a given VENDINFO file. Further tests for those particular errorlevels should be unnecessary. VendPrcs Processor v1.00 -66- Dec 1993